docs: add architecture diagram and overview by jyaunches · Pull Request #1095 · NVIDIA/NemoClaw

jyaunches · 2026-03-30T14:54:46Z

Summary

Adds an Architecture section to the README with:

Mermaid diagram showing the relationship between NemoClaw and OpenShell
Explanatory text clarifying what each layer provides

What the diagram shows

NemoClaw (green): Onboarding, Messaging Bridges, Blueprint, State Management
OpenShell (dark): Gateway, CLI, Sandbox container
Data flows: Credential-safe inference path, message relay via SSH, policy-gated egress

Key message

OpenShell handles how to sandbox an agent securely. NemoClaw handles what goes in the sandbox and makes the setup accessible.

Screenshots

The mermaid diagram renders natively on GitHub. Preview in the Files Changed tab.

Summary by CodeRabbit

Documentation
- Added Architecture section to README explaining NemoClaw's layered structure on top of OpenShell, covering onboarding, blueprint hardening, state management, and messaging bridges. Includes a comprehensive system diagram showing control and data flow between the CLI, messaging bridges, gateway, sandbox container, and external services like inference providers and messaging platforms.

- Add mermaid diagram showing NemoClaw/OpenShell relationship - Explain what each layer provides (onboarding, blueprint, state, bridges) - Clarify that OpenShell is the runtime, NemoClaw is the opinionated stack

coderabbitai · 2026-03-30T14:55:05Z

📝 Walkthrough

Walkthrough

The README.md file was updated with a new "Architecture" section that documents NemoClaw's layered design as an opinionated stack built on OpenShell. The section includes a tabular breakdown of architectural layers and a Mermaid diagram illustrating the end-to-end control and data flow across components.

Changes

Cohort / File(s)	Summary
Documentation `README.md`	Added "Architecture" section with layer-by-layer breakdown and Mermaid diagram detailing NemoClaw's stack design, component interactions, and data/control flow between CLI, messaging bridges, OpenShell gateway, sandbox container, and external services.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A rabbit's tale of architecture fine,
NemoClaw's layers, all in line,
With diagrams drawn and flows on show,
The README now helps all to know! 🏗️

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: adding documentation (architecture diagram and overview) to the README.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Line 49: Replace the emoji labels in the Mermaid diagram nodes with plain
text: change the USER node label USER(["👤 User"]):::user to
USER(["User"]):::user (and the Auth/lock node that uses "🔒"—e.g. AUTH(["🔒
Auth"]):::auth—to AUTH(["Auth"]):::auth); update any other diagram node labels
containing emojis to their plain-text equivalents so README.md follows the "No
emoji in technical prose" rule.
- Line 70: Update the diagram node text that currently reads OSCLI["openshell
CLI<br/><small>provider · sandbox<br/>gateway · policy</small>"]:::openshell to
use the correct product casing: change "openshell CLI" to "OpenShell CLI" while
keeping the rest of the label (the HTML line breaks and small text) unchanged so
the node still reads OSCLI["OpenShell CLI<br/><small>provider ·
sandbox<br/>gateway · policy</small>"]:::openshell.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7c3cecae-3422-40db-ac1a-562c8a6fa8c1

📥 Commits

Reviewing files that changed from the base of the PR and between 3c7bd93 and 0cdc086.

📒 Files selected for processing (1)

README.md

coderabbitai · 2026-03-30T14:57:10Z

README.md

+    classDef external fill:#f5f5f5,stroke:#e0e0e0,color:#1a1a1a,stroke-width:1px
+    classDef user fill:#fff,stroke:#76b900,color:#1a1a1a,stroke-width:2px,font-weight:bold
+
+    USER(["👤 User"]):::user


⚠️ Potential issue | 🟡 Minor

Remove emoji from diagram labels in technical prose.

Line 49 (👤) and Line 72 (🔒) violate the Markdown prose rule; please replace with plain text labels.

As per coding guidelines, "**/*.md ... No emoji in technical prose."

Also applies to: 72-72

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed. In `@README.md` at line 49, Replace the emoji labels in the Mermaid diagram nodes with plain text: change the USER node label USER(["👤 User"]):::user to USER(["User"]):::user (and the Auth/lock node that uses "🔒"—e.g. AUTH(["🔒 Auth"]):::auth—to AUTH(["Auth"]):::auth); update any other diagram node labels containing emojis to their plain-text equivalents so README.md follows the "No emoji in technical prose" rule.

coderabbitai · 2026-03-30T14:57:11Z

README.md

+        subgraph OPENSHELL["OpenShell"]
+            direction TB
+            GW["Gateway<br/><small>Credential store<br/>Inference proxy<br/>Policy engine<br/>Device auth</small>"]:::openshell
+            OSCLI["openshell CLI<br/><small>provider · sandbox<br/>gateway · policy</small>"]:::openshell


⚠️ Potential issue | 🟡 Minor

Fix product casing in diagram node text.

Line 70 uses openshell CLI; this should be OpenShell CLI to match required product casing.

As per coding guidelines, "**/*.md ... NemoClaw, OpenClaw, and OpenShell must use correct casing."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed. In `@README.md` at line 70, Update the diagram node text that currently reads OSCLI["openshell CLI provider · sandbox gateway · policy"]:::openshell to use the correct product casing: change "openshell CLI" to "OpenShell CLI" while keeping the rest of the label (the HTML line breaks and small text) unchanged so the node still reads OSCLI["OpenShell CLI provider · sandbox gateway · policy"]:::openshell.

docs: add architecture diagram and overview

0cdc086

- Add mermaid diagram showing NemoClaw/OpenShell relationship - Explain what each layer provides (onboarding, blueprint, state, bridges) - Clarify that OpenShell is the runtime, NemoClaw is the opinionated stack

coderabbitai bot reviewed Mar 30, 2026

View reviewed changes

jyaunches mentioned this pull request Mar 30, 2026

Add architecture diagram and overview to README #1098

Closed

cv approved these changes Mar 30, 2026

View reviewed changes

cv merged commit c01bd83 into NVIDIA:main Mar 30, 2026
11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add architecture diagram and overview#1095

docs: add architecture diagram and overview#1095
cv merged 1 commit intoNVIDIA:mainfrom
jyaunches:docs/architecture-diagram

jyaunches commented Mar 30, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Mar 30, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot Mar 30, 2026

Uh oh!

coderabbitai bot Mar 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jyaunches commented Mar 30, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What the diagram shows

Key message

Screenshots

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jyaunches commented Mar 30, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 30, 2026 •

edited

Loading